Layouts Overview
================

Box Layout
----------

The Box layout organizes widgets into rows and columns. In v0.3.0, ``Box``
accepts additional parameters for sizing, styling, and identification.

.. code:: python

   Box([
       [Text('Row 1')],
       [Text('Row 2'), Button('Click')]
   ])

.. _key-attributes-10:

**Key Attributes:**

-  **widgets** (list): A nested list defining the structure of rows and
   columns.

-  **css** (str): Inline CSS string applied to the Box container.

-  **margin** (tuple | int): Margin around the box content.

-  **spacing** (int): Spacing between widgets inside the box.

-  **size** (tuple): Preferred size as ``(width, height)``.

-  **fixed_size** (tuple): Fixed size as ``(width, height)``.

-  **min_size** (tuple): Minimum size as ``(width, height)``.

-  **max_size** (tuple): Maximum size as ``(width, height)``.

-  **id** (any): Identifier for dynamic retrieval via ``GET()``.

.. _example-7:

**Example:**

.. code:: python

   from clera import Box, Text, Button

   Box(
       [
           [Text('Row 1 Text')],
           [Button(value='Row 2 Button')]
       ],
       margin=10,
       spacing=5,
       id='-main-box-'
   )


Grid Layout
-----------

The Grid layout arranges widgets in a tabular structure based on
specified rows and columns. Accepts the same extended parameters as Box.

.. code:: python

   Grid([
       [Text('Row 1')],
       [Text('Row 2'), Button('Click')]
   ])

.. _key-attributes-11:

**Key Attributes:**

-  **widgets** (list): A nested list defining the structure of rows and
   columns.

-  **css** (str): Inline CSS string applied to the Grid container.

-  **margin** (tuple | int): Margin around the grid content.

-  **spacing** (int): Spacing between widgets.

-  **size** (tuple): Preferred size as ``(width, height)``.

-  **fixed_size** (tuple): Fixed size as ``(width, height)``.

-  **min_size** (tuple): Minimum size as ``(width, height)``.

-  **max_size** (tuple): Maximum size as ``(width, height)``.

-  **id** (any): Identifier for dynamic retrieval via ``GET()``.


Splitter
--------

The **Splitter** layout divides the window into resizable panes. The
user can drag the divider handle at runtime to resize panes. Supports
horizontal and vertical orientation.

.. code:: python

   Splitter(widgets=[layout1, layout2], orientation='horizontal')

.. _key-attributes-splitter:

**Key Attributes:**

-  **widgets** (list): A list of layouts or widgets to place in each pane.

-  **orientation** (str): ``'horizontal'`` or ``'vertical'``. Defaults to ``'horizontal'``.

-  **sizes** (list): Initial pixel sizes for each pane, e.g. ``[200, 400]``.

-  **handle_width** (int): Width of the drag handle in pixels. Defaults to ``5``.

-  **live_resize** (bool): If ``True``, panes resize in real time while dragging. Defaults to ``True``.

-  **collapsible** (bool): Allows panes to be collapsed to zero width. Defaults to ``True``.

-  **state** (any): Restores a previously saved splitter state.

-  **id** (any): Identifier for dynamic retrieval via ``GET()``.

.. _example-splitter:

**Example:**

.. code:: python

   from clera import Window, Box, Splitter, Text, ListWidget

   window = Window()

   sidebar = Box([[ListWidget(list_items=['File 1', 'File 2', 'File 3'])]])
   content = Box([[Text('Select a file from the sidebar', alignment='center')]])

   Splitter(
       widgets=[sidebar, content],
       orientation='horizontal',
       sizes=[200, 600],
       handle_width=4
   )

   window.run()


Stack
-----

The **Stack** widget manages multiple widgets in a stacked layout, where
only one is visible at a time.

.. code:: python

   Stack(widgets=[layout1, layout2])

.. _key-attributes-12:

**Key Attributes:**

-  **widgets (list):** A list of widgets to stack.

.. _example-8:

**Example:**

.. code:: python

   first_layout = Box([[Text('First View')]])
   second_layout = Box([[Text('Second View')]])

   Stack(
      widgets=[
         first_layout,
         second_layout,
      ]
   )


Column
------

The **Column** layout places widgets in a single vertical column.
In v0.3.0, ``Column`` accepts ``margin`` and ``spacing`` parameters.

.. code:: python

   Column(widgets=[widget1, widget2], margin=5, spacing=4)

**Key Attributes:**

-  **widgets** (list): Widgets to place in the column.

-  **margin** (tuple): Margin around the column content.

-  **spacing** (tuple): Spacing between widgets.


Additional Layout Features
--------------------------

**Group Layout**

The Group layout organizes button widgets within a container. It
supports vertical or horizontal orientation and allows nesting other
layouts within.

.. _key-attributes-13:

**Key Attributes:**

-  **widgets** (list): List of child button widgets.

-  **orientation** (str): ``vertical`` or ``horizontal``.

-  **strict** (bool): Enforces strict alignment of child widgets if
   True.

.. _example-9:

**Example:**

.. code:: python

   from clera import Group, Button, Text

   group(
       widgets=[
           Button(value='Action 1'),
           Button(value='Action 2')
       ],
       orientation='vertical'
   )


**Fieldset Layout**

The Fieldset layout groups related widgets together under a labeled
border, making it ideal for forms or sections.

.. _key-attributes-14:

**Key Attributes:**

-  **label** (str): Title of the fieldset.

-  **widgets** (list): List of widgets inside the fieldset.

-  **orientation** (str): ``vertical`` or ``horizontal``.

.. _example-10:

**Example:**

.. code:: python

   from clera import Fieldset, Input, Button

   fieldset(
       label='Login Details',
       widgets=[
           Input(placeholder='Username'),
           Input(placeholder='Password', type='password'),
           Button(value='Login')
       ],
       orientation='vertical'
   )